Skip to content

feat(pg:promote): support pg:promote on Advanced-tier databases - #4068

Draft
ekozilforce wants to merge 5 commits into
mainfrom
ekozil/pg-promote-advanced
Draft

ekozilforce wants to merge 5 commits into
mainfrom
ekozil/pg-promote-advanced

Conversation

@ekozilforce

@ekozilforce ekozilforce commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

data-api rejects the legacy /client/v11 wait_status and database endpoints for Advanced-tier databases, so pg:promote failed with not_allowed_on_advanced. For Advanced databases, use the /data/postgres/v1 wait_status endpoint, warn on non-leader pool attachments instead of checking follower status, and skip reattaching the connection-pooling:default pooler.

Type of Change

Breaking Changes (major semver update)

  • Add a ! after your change type to denote a change that breaks current behavior

Feature Additions (minor semver update)

  • feat: Introduces a new feature to the codebase

Patch Updates (patch semver update)

  • fix: Bug fix
  • deps: Dependency upgrade
  • revert: Revert a previous commit
  • chore: Change that does not affect production code
  • refactor: Refactoring existing code without changing behavior
  • test: Add/update/remove tests

Testing

Notes:

Testing

Notes:

  • Step 1 runs against ekozil-dev-private on the regular data service. Steps 2–5 run against ekozil-dev (dev data service) with HEROKU_DATA_SERVICE=heroku-postgresql-ekozil exported. All of them use ./bin/run.js from this branch.
  • On ekozil-dev, both databases are Advanced tier: postgresql-ekozil-opaque-41919 (PG17) and postgresql-ekozil-perpendicular-69151 (PG18).
  • opaque-41919 is the target of an in-progress data migration, so its wait_status reports waiting. That makes it a natural test for the waiting check.
  • Request bodies were captured with DEBUG=http.
  • namespaces lists the two ekozil-dev databases' attachments and their namespaces from the Platform API:
namespaces() {
  curl -s https://api.heroku.com/apps/ekozil-dev/addon-attachments \
    -H 'Accept: application/vnd.heroku+json; version=3' \
    -H "Authorization: Bearer $(heroku auth:token)" |
    jq -r '.[]
      | select(.addon.name | test("opaque-41919|perpendicular"))
      | [.name, .addon.name, .namespace // "null"]
      | @tsv' |
    column -t
}

Starting state on ekozil-dev:

% namespaces
DATABASE                          postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_CRIMSON  postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_MAROON   postgresql-ekozil-perpendicular-69151  null

Steps:

1. Classic → Advanced in a Private Space

Setup: a classic private-0 database is attached as DATABASE, and an advanced-private database is attached as AMBER. Promote the Advanced database.

% heroku addons --app ekozil-dev-private

  Add-on                                             Plan               Price          Max Price    State
  ───────────────────────────────────────────────────────────────────────────────────────────────────────────
  heroku-postgresql (postgresql-reticulated-83748)   advanced-private   metered        metered      created
  └─ as HEROKU_POSTGRESQL_AMBER

  heroku-postgresql (postgresql-convex-91319)        private-0          ~$0.417/hour   $300/month   created
  └─ as DATABASE


The table above shows add-ons and the attachments to the current app (⬢ ekozil-dev-private) or other apps.

% ./bin/run.js data:pg:promote postgresql-reticulated-83748 -a ekozil-dev-private
Ensuring an alternate alias for existing ⛁ DATABASE_URL... HEROKU_POSTGRESQL_COBALT_URL
Promoting ⛁ postgresql-reticulated-83748 to ⛁ DATABASE_URL on ⬢ ekozil-dev-private... done

Result: the classic database gets the COBALT alias, and the Advanced database becomes DATABASE.

2. Advanced over Advanced, targeting the add-on name

Setup: DATABASE is opaque, which also has the CRIMSON alias. Promote perpendicular by its add-on name.

% ./bin/run.js pg:promote postgresql-ekozil-perpendicular-69151 -a ekozil-dev
Ensuring an alternate alias for existing DATABASE_URL... HEROKU_POSTGRESQL_EKOZIL_CRIMSON_URL
Promoting postgresql-ekozil-perpendicular-69151 to DATABASE_URL on ekozil-dev... done

Request body:

{"addon":{"name":"postgresql-ekozil-perpendicular-69151"},"app":{"name":"ekozil-dev"},"confirm":"ekozil-dev","name":"D
ATABASE","namespace":null}

Result: the existing CRIMSON alias is reused, the /data/postgres/v1 wait_status returns not waiting, and DATABASE moves to perpendicular with no namespace.

% namespaces
DATABASE                          postgresql-ekozil-perpendicular-69151  null
HEROKU_POSTGRESQL_EKOZIL_CRIMSON  postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_MAROON   postgresql-ekozil-perpendicular-69151  null

3. Namespaced attachment, targeting the attachment name

Setup: create an attachment that uses the leader pool and the owner credential.

% ./bin/run.js data:pg:attachments:create postgresql-ekozil-perpendicular-69151 -a ekozil-dev --as PROMOTE_TEST --pool
leader --credential u6s5a0bl7sm38d
Attaching postgresql-ekozil-perpendicular-69151 with credential u6s5a0bl7sm38d and pool leader as PROMOTE_TEST to
ekozil-dev... done
Setting PROMOTE_TEST config vars and restarting ekozil-dev... done, v1850

% ./bin/run.js pg:promote PROMOTE_TEST -a ekozil-dev
Ensuring an alternate alias for existing DATABASE_URL... HEROKU_POSTGRESQL_EKOZIL_MAROON_URL
Promoting PROMOTE_TEST to DATABASE_URL on ekozil-dev... done

Request body:

{"addon":{"name":"postgresql-ekozil-perpendicular-69151"},"app":{"name":"ekozil-dev"},"confirm":"ekozil-dev","name":"D
ATABASE","namespace_config":{"pool":"leader","proxy":"false","role":"u6s5a0bl7sm38d"}}

Result: DATABASE gets the same namespace as PROMOTE_TEST and the same URL, so no new credential was created. There's no follower-pool warning, because the pool is leader.

% namespaces
DATABASE                          postgresql-ekozil-perpendicular-69151  pool:leader|proxy:false|role:u6s5a0bl7sm38d
HEROKU_POSTGRESQL_EKOZIL_CRIMSON  postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_MAROON   postgresql-ekozil-perpendicular-69151  null
PROMOTE_TEST                      postgresql-ekozil-perpendicular-69151  pool:leader|proxy:false|role:u6s5a0bl7sm38d

% for v in DATABASE_URL PROMOTE_TEST_URL; do echo "$v $(heroku config:get $v -a ekozil-dev | shasum -a 256 | cut
-c1-12)"; done
DATABASE_URL 8c1ff6c253d4
PROMOTE_TEST_URL 8c1ff6c253d4

4. Namespaced DATABASE with no other alias, promoting a database that's waiting

Setup: detach PROMOTE_TEST, so nothing else has DATABASE's namespace. Then promote opaque, which is still waiting on its migration.

% heroku addons:detach PROMOTE_TEST -a ekozil-dev
Detaching PROMOTE_TEST to postgresql-ekozil-perpendicular-69151 from ekozil-dev... done
Unsetting PROMOTE_TEST config vars and restarting ekozil-dev... done, v1853

% ./bin/run.js pg:promote postgresql-ekozil-opaque-41919 -a ekozil-dev
Ensuring an alternate alias for existing DATABASE_URL... HEROKU_POSTGRESQL_EKOZIL_ONYX_URL
  ›   Error: Database cannot be promoted while in state: Migration is ready.
  ›   Check your email for details.
  ›
  ›   Promoting this database can lead to application errors and outage. Please
  ›   run heroku data:pg:wait to wait for database to become available.
  ›
  ›   To ignore this error, you can pass the --force flag to promote the
  ›   database and risk application issues.
  ›

Request body for the alias (sent after GET /addons/bc837405-… to look up the current DATABASE's tier):

{"addon":{"name":"postgresql-ekozil-perpendicular-69151"},"app":{"name":"ekozil-dev"},"confirm":"ekozil-dev","namespac
e_config":{"pool":"leader","proxy":"false","role":"u6s5a0bl7sm38d"}}

Result: the ONYX alias is created with DATABASE's exact namespace and URL. Promotion then stops at the wait check and points to data:pg:wait. DATABASE is unchanged.

% namespaces
DATABASE                          postgresql-ekozil-perpendicular-69151  pool:leader|proxy:false|role:u6s5a0bl7sm38d
HEROKU_POSTGRESQL_EKOZIL_CRIMSON  postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_MAROON   postgresql-ekozil-perpendicular-69151  null
HEROKU_POSTGRESQL_EKOZIL_ONYX     postgresql-ekozil-perpendicular-69151  pool:leader|proxy:false|role:u6s5a0bl7sm38d

% for v in DATABASE_URL HEROKU_POSTGRESQL_EKOZIL_ONYX_URL; do echo "$v $(heroku config:get $v -a ekozil-dev | shasum
-a 256 | cut -c1-12)"; done
DATABASE_URL 8c1ff6c253d4
HEROKU_POSTGRESQL_EKOZIL_ONYX_URL 8c1ff6c253d4

5. --force past the wait check

% ./bin/run.js pg:promote postgresql-ekozil-opaque-41919 -a ekozil-dev --force
Ensuring an alternate alias for existing DATABASE_URL... HEROKU_POSTGRESQL_EKOZIL_ONYX_URL
Promoting postgresql-ekozil-opaque-41919 to DATABASE_URL on ekozil-dev... done

Request body:

{"addon":{"name":"postgresql-ekozil-opaque-41919"},"app":{"name":"ekozil-dev"},"confirm":"ekozil-dev","name":"DATABASE ","namespace":null}

Result: the ONYX alias from step 4 is reused, wait_status isn't called, and DATABASE is back on opaque.

% namespaces
DATABASE                          postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_CRIMSON  postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_MAROON   postgresql-ekozil-perpendicular-69151  null
HEROKU_POSTGRESQL_EKOZIL_ONYX     postgresql-ekozil-perpendicular-69151  pool:leader|proxy:false|role:u6s5a0bl7sm38d

Cleanup:

% heroku addons:detach HEROKU_POSTGRESQL_EKOZIL_ONYX -a ekozil-dev
Detaching HEROKU_POSTGRESQL_EKOZIL_ONYX to postgresql-ekozil-perpendicular-69151 from ekozil-dev... done
Unsetting HEROKU_POSTGRESQL_EKOZIL_ONYX config vars and restarting ekozil-dev... done, v1857

% namespaces
DATABASE                          postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_CRIMSON  postgresql-ekozil-opaque-41919         null
HEROKU_POSTGRESQL_EKOZIL_MAROON   postgresql-ekozil-perpendicular-69151  null

Screenshots (if applicable)

Screenshot 2026-11-12 at 8 47 35 AM

Related Issues

GUS work item: W-20250296

@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:32 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:32 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:32 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:32 — with GitHub Actions Active
@github-actions github-actions Bot added the size/M Medium PR (code churn < 500) label Nov 12, 2026
data-api rejects the legacy /client/v11 wait_status and database endpoints for Advanced-tier databases, so pg:promote failed with not_allowed_on_advanced. For Advanced databases, use the /data/postgres/v1 wait_status endpoint, warn on non-leader pool attachments instead of checking follower status, and skip reattaching the connection-pooling:default pooler.
@ekozilforce
ekozilforce force-pushed the ekozil/pg-promote-advanced branch from 6e72f2e to b4e0e85 Compare November 12, 2026 12:34
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:34 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:34 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:34 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:34 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:44 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:44 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:44 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 12:44 — with GitHub Actions Active
Platform API is deprecating the raw namespace param on addon-attachment creation. Namespaced Advanced attachments are now sent as namespace_config, both for the promoted attachment and for the alias created for the current DATABASE. Platform only returns the namespace string it built from that config, so it's split back into its key/value pairs and resolves to the same existing namespace. Legacy-tier request bodies are unchanged.
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 15:39 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 15:39 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 15:39 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 15:39 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 16:19 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 16:19 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 16:19 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 12, 2026 16:19 — with GitHub Actions Active
@ekozilforce ekozilforce changed the title feat(pg): support pg:promote on Advanced-tier databases feat(pg:promote): support pg:promote on Advanced-tier databases Nov 16, 2026
Database cannot be promoted while in state: ${status.message}

Promoting this database can lead to application errors and outage. Please run ${color.code('heroku pg:wait')} to wait for database to become available.
Promoting this database can lead to application errors and outage. Please run ${color.code(waitCommand)} to wait for database to become available.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use this opportunity to get a CX pass for this older sentence?

E.g., as an idea:

Promotion failed: database is currently ${status.message}.

Promoting in this state risks app errors and downtime. Run ${color.code(waitCommand)} to wait until the database is available, or re-run with ${color.code('--force')} to override.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I'll run it by cx

ux.warn(heredoc(`
${color.attachment(currentPooler.name + '_URL')} still points to ${color.addon(current?.addon?.name as string)}.

${color.code('heroku pg:promote')} doesn't reattach connection pooling to Advanced-tier databases.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With Advanced not supporting server-side connection pooling at the moment, we could recommend the customer to detach the pool config var.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This prob should run through cx too, I'll draft something up

@ekozilforce
ekozilforce deployed to AcceptanceTests November 19, 2026 20:45 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 19, 2026 20:45 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 19, 2026 20:45 — with GitHub Actions Active
@ekozilforce
ekozilforce deployed to AcceptanceTests November 19, 2026 20:45 — with GitHub Actions Active

This branch was successfully deployed

1 active deployment
AcceptanceTests — fca91e2e Deployed Nov 19, 2026 by ekozilforce via acceptance (22.x, ubuntu-latest) #9811
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/M Medium PR (code churn < 500)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants